crypto

Overview

The crypto module provides a set of cryptographic primitives like digests, ciphers and other cryptographic algorithms in pure Lua. It offers several functionalities to hash, encrypt and decrypt data, simplifying the development of secure communication and data storage. This document will guide you through the module's functionalities, installation, and usage.

Usage

lua

local crypto = require(".crypto");

Primitives

Digests (sha1, sha2, sha3, keccak, blake2b, etc.)
Ciphers (AES, ISSAC, Morus, NORX, etc.)
Random Number Generators (ISAAC)
MACs (HMAC)
KDFs (PBKDF2)
Utilities (Array, Stream, Queue, etc.)

Digests

MD2

Calculates the MD2 digest of a given message.

Parameters:
- stream (Stream): The message in form of stream
Returns: A table containing functions to get digest in different formats.
- asBytes(): The digest as byte table.
- asHex(): The digest as string in hexadecimal format.
- asString(): The digest as string format.

Example:

lua

local str = crypto.utils.stream.fromString("ao")

return crypto.digest.md2(str).asHex() -- 0d4e80edd07bee6c7965b21b25a9b1ea

MD4

Calculates the MD4 digest of a given message.

Parameters:
- stream (Stream): The message in form of stream
Returns: A table containing functions to get digest in different formats.
- asBytes(): The digest as byte table.
- asHex(): The digest as string in hexadecimal format.
- asString(): The digest as string format.

Example:

lua

local str = crypto.utils.stream.fromString("ao")

return crypto.digest.md4(str).asHex() -- e068dfe3d8cb95311b58be566db66954

MD5

Calculates the MD5 digest of a given message.

Parameters:
- stream (Stream): The message in form of stream
Returns: A table containing functions to get digest in different formats.
- asBytes(): The digest as byte table.
- asHex(): The digest as string in hexadecimal format.
- asString(): The digest as string format.

Example:

lua

local str = crypto.utils.stream.fromString("ao")

return crypto.digest.md5(str).asHex() -- adac5e63f80f8629e9573527b25891d3

SHA1

Calculates the SHA1 digest of a given message.

Parameters:
- stream (Stream): The message in form of stream
Returns: A table containing functions to get digest in different formats.
- asBytes(): The digest as byte table.
- asHex(): The digest as string in hexadecimal format.
- asString(): The digest as string format.

Example:

lua

local str = crypto.utils.stream.fromString("ao")

return crypto.digest.sha1(str).asHex() -- c29dd6c83b67a1d6d3b28588a1f068b68689aa1d

SHA2_256

Calculates the SHA2-256 digest of a given message.

Parameters:
- stream (Stream): The message in form of stream
Returns: A table containing functions to get digest in different formats.
- asBytes(): The digest as byte table.
- asHex(): The digest as string in hexadecimal format.
- asString(): The digest as string format.

Example:

lua

local str = crypto.utils.stream.fromString("ao")

return crypto.digest.sha2_256(str).asHex() -- ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

SHA2_512

Calculates the SHA2-512 digest of a given message.

Parameters:
- msg (string): The message to calculate the digest
Returns: A table containing functions to get digest in different formats.
- asBytes(): The digest as byte table.
- asHex(): The digest as string in hexadecimal format.
- asString(): The digest as string format.

Example:

lua

local str = "ao"

return crypto.digest.sha2_512(str).asHex() -- 6f36a696b17ce5a71efa700e8a7e47994f3e134a5e5f387b3e7c2c912abe94f94ee823f9b9dcae59af99e2e34c8b4fb0bd592260c6720ee49e5deaac2065c4b1

SHA3

It contains the following functions:

sha3_256
sha3_512
keccak256
keccak512

Each function calculates the respective digest of a given message.

Parameters:
- msg (string): The message to calculate the digest
Returns: A table containing functions to get digest in different formats.
- asBytes(): The digest as byte table.
- asHex(): The digest as string in hexadecimal format.
- asString(): The digest as string format.

Example:

lua


local str = "ao"

crypto.digest.sha3_256(str).asHex()  -- 1bbe785577db997a394d5b4555eec9159cb51f235aec07514872d2d436c6e985
crypto.digest.sha3_512(str).asHex()  -- 0c29f053400cb1764ce2ec555f598f497e6fcd1d304ce0125faa03bb724f63f213538f41103072ff62ddee701b52c73e621ed4d2254a3e5e9a803d83435b704d
crypto.digest.keccak256(str).asHex() -- 76da52eec05b749b99d6e62bb52333c1569fe75284e6c82f3de12a4618be00d6
crypto.digest.keccak512(str).asHex() -- 046fbfad009a12cef9ff00c2aac361d004347b2991c1fa80fba5582251b8e0be8def0283f45f020d4b04ff03ead9f6e7c43cc3920810c05b33b4873b99affdea

Blake2b

Calculates the Blake2b digest of a given message.

Parameters:
- data (string): The data to be hashed.
- outlen (number): The length of the output hash (optional) default is 64.
- key (string): The key to be used for hashing (optional) default is "".
Returns: A table containing functions to get digest in different formats.
- asBytes(): The digest as byte table.
- asHex(): The digest as string in hexadecimal format.
- asString(): The digest as string format.

Example:

lua

local str = "ao"

crypto.digest.blake2b(str).asHex() -- 576701fd79a126f2c414ef94adf1117c88943700f312679d018c29c378b2c807a3412b4e8d51e191c48fb5f5f54bf1bca29a714dda166797b3baf9ead862ae1d
crypto.digest.blake2b(str, 32).asHex() -- 7050811afc947ba7190bb3c0a7b79b4fba304a0de61d529c8a35bdcbbb5544f4
crypto.digest.blake2b(str, 32, "secret_key").asHex() -- 203c101980fdf6cf24d78879f2e3db86d73d91f7d60960b642022cd6f87408f8

Ciphers

AES

The Advanced Encryption Standard (AES) is a symmetric block cipher used to encrypt sensitive information. It has two functions encrypt and decrypt.

Encrypt

Encrypts a given message using the AES algorithm.

Parameters:
- data (string): The data to be encrypted.
- key (string): The key to be used for encryption.
- iv (string) optional: The initialization vector to be used for encryption. default is ""
- mode (string) optional: The mode of operation to be used for encryption. default is "CBC". Available modes are CBC, ECB, CFB, OFB, CTR.
- keyLength (number) optional: The length of the key to use for encryption. default is 128.
Returns: A table containing functions to get encrypted data in different formats.
- asBytes(): The encrypted data as byte table.
- asHex(): The encrypted data as string in hexadecimal format.
- asString(): The encrypted data as string format.

Decrypt

Decrypts a given message using the AES algorithm.

Parameters:
- cipher (string): Hex Encoded encrypted data.
- key (string): The key to be used for decryption.
- iv (string) optional: The initialization vector to be used for decryption. default is ""
- mode (string) optional: The mode of operation to be used for decryption. default is "CBC". Available modes are CBC, ECB, CFB, OFB, CTR.
- keyLength (number) optional: The length of the key to use for decryption. default is 128.
Returns: A table containing functions to get decrypted data in different formats.
- asBytes(): The decrypted data as byte table.
- asHex(): The decrypted data as string in hexadecimal format.
- asString(): The decrypted data as string format.

Example:

lua

local str = "ao"

local iv = "super_secret_shh"
local key_128 = "super_secret_shh"

local encrypted = crypto.cipher.aes.encrypt("ao", key, iv).asHex() -- A3B9E6E1FBD9D46930E5F76807C84B8E
local decrypted = crypto.cipher.aes.decrypt(encrypted, key, iv).asHex() -- 616F0000000000000000000000000000

crypto.utils.hex.hexToString(decrypted) -- ao

ISSAC Cipher

ISAAC is a cryptographically secure pseudo-random number generator (CSPRNG) and stream cipher. It has the following functions

seedIsaac: Seeds the ISAAC cipher with a given seed.
getRandomChar: Generates a random character using the ISAAC cipher.
random: Generates a random number between a given range using the ISAAC cipher.
getRandom: Generates a random number using the ISAAC cipher.
encrypt: Encrypts a given message using the ISAAC cipher.
decrypt: Decrypts a given message using the ISAAC cipher.

Encrypt

Encrypts a given message using the ISAAC cipher.

Parameters:
- msg (string): The message to be encrypted.
- key (string): The key to be used for encryption.
Returns: A table containing functions to get encrypted data in different formats.
- asBytes(): The encrypted data as byte table.
- asHex(): The encrypted data as string in hexadecimal format.
- asString(): The encrypted data as string format.

Decrypt

Decrypts a given message using the ISAAC cipher.

Parameters:
- cipher (string): Hex Encoded encrypted data.
- key (string): Key to be used for decryption.
Returns: A table containing functions to get decrypted data in different formats.
- asBytes(): The decrypted data as byte table.
- asHex(): The decrypted data as string in hexadecimal format.
- asString(): The decrypted data as string format.

Example:

lua

local message = "ao";
local key = "secret_key";

local encrypted = crypto.cipher.issac.encrypt(message, key)
local decrypted = crypto.cipher.issac.decrypt(encrypted.asString(), key) -- ao


encrypted.asHex() -- 7851

random

Generates a random number using the ISAAC cipher.

Parameters:
- min (number) optional: The minimum value of the random number. defaults to 0.
- max (number) optional: The maximum value of the random number. defaults to 2^31 - 1.
- seed (string) optional: The seed to be used for generating the random number. defaults to math.random(0,2^32 - 1).
Returns: A random number between the given range.

Example:

lua

crypto.cipher.issac.random(0, 100) -- 42

Morus Cipher

MORUS is a high-performance authenticated encryption algorithm submitted to the CAESAR competition, and recently selected as a finalist.

Encrypt

Encrypts a given message using the MORUS cipher.

Parameters:
- key (string): The encryption key (16 or 32-byte string).
- iv (string): The nonce or initial value (16-byte string).
- msg (string): The message to encrypt (variable length string).
- ad (string) optional: The additional data (variable length string). defaults to "".
Returns: A table containing functions to get encrypted data in different formats.
- asBytes(): The encrypted data as byte table.
- asHex(): The encrypted data as string in hexadecimal format.
- asString(): The encrypted data as string format.

Decrypt

Decrypts a given message using the MORUS cipher.

Parameters:
- key (string): The encryption key (16 or 32-byte string).
- iv (string): The nonce or initial value (16-byte string).
- cipher (string): The encrypted message (variable length string).
- adLen (number) optional: The length of the additional data (variable length string). defaults to 0.
Returns: A table containing functions to get decrypted data in different formats.
- asBytes(): The decrypted data as byte table.
- asHex(): The decrypted data as string in hexadecimal format.
- asString(): The decrypted data as string format.

Example:

lua

local m = "ao"
local k = "super_secret_shh"
local iv = "0000000000000000"
local ad= ""

local e = crypto.cipher.morus.encrypt(k, iv, m, ad)
local d = crypto.cipher.morus.decrypt(k, iv, e.asString(), #ad) -- ao

e.asHex() -- 514ed31473d8fb0b76c6cbb17af35ed01d0a

NORX Cipher

NORX is an authenticated encryption scheme with associated data that was selected, along with 14 other primitives, for the third phase of the ongoing CAESAR competition. It is based on the sponge construction and relies on a simple permutation that allows efficient and versatile implementations.

Encrypt

Encrypts a given message using the NORX cipher.

Parameters:
- key (string): The encryption key (32-byte string).
- nonce (string): The nonce or initial value (32-byte string).
- plain (string): The message to encrypt (variable length string).
- header (string) optional: The additional data (variable length string). defaults to "".
- trailer (string) optional: The additional data (variable length string). defaults to "".
Returns: A table containing functions to get encrypted data in different formats.
- asBytes(): The encrypted data as byte table.
- asHex(): The encrypted data as string in hexadecimal format.
- asString(): The encrypted data as string format.

Decrypt

Decrypts a given message using the NORX cipher.

Parameters:
- key (string): The encryption key (32-byte string).
- nonce (string): The nonce or initial value (32-byte string).
- crypted (string): The encrypted message (variable length string).
- header (string) optional: The additional data (variable length string). defaults to "".
- trailer (string) optional: The additional data (variable length string). defaults to "".
Returns: A table containing functions to get decrypted data in different formats.
- asBytes(): The decrypted data as byte table.
- asHex(): The decrypted data as string in hexadecimal format.
- asString(): The decrypted data as string format.

Example:

lua

local key = "super_duper_secret_password_shhh"
local nonce = "00000000000000000000000000000000"

local data = "ao"

-- Header and trailer are optional
local header, trailer = data, data

local encrypted = crypto.cipher.norx.encrypt(key, nonce, data, header, trailer).asString()
local decrypted = crypto.cipher.norx.decrypt(key, nonce, encrypted, header, trailer) -- ao

local authTag = encrypted:sub(#encrypted-32+1)

crypto.utils.hex.stringToHex(encrypted) -- 0bb35a06938e6541eccd4440adb7b46118535f60b09b4adf378807a53df19fc4ea28
crypto.utils.hex.stringToHex(authTag) -- 5a06938e6541eccd4440adb7b46118535f60b09b4adf378807a53df19fc4ea28

Random Number Generators

The module contains a random number generator using ISAAC which is a cryptographically secure pseudo-random number generator (CSPRNG) and stream cipher.

Parameters:
- min (number) optional: The minimum value of the random number. defaults to 0.
- max (number) optional: The maximum value of the random number. defaults to 2^31 - 1.
- seed (string) optional: The seed to be used for generating the random number. defaults to math.random(0,2^32 - 1).
Returns: A random number between the given range.

Example:

lua

crypto.random.(0, 100, "seed") -- 42

MACs

HMAC

The Hash-based Message Authentication Code (HMAC) is a mechanism for message authentication using cryptographic hash functions. HMAC can be used with any iterative cryptographic hash function, e.g., MD5, SHA-1, in combination with a secret shared key.

The modules exposes a function called createHmac which is used to create a HMAC instance.

Parameters:
- data (Stream): The data to be hashed.
- key (Array): The key to be used for hashing.
- algorithm (string) optional: The algorithm to be used for hashing. default is "sha256". Available algorithms are "sha1", "sha256". default is "sha1".
Returns: A table containing functions to get HMAC in different formats.
- asBytes(): The HMAC as byte table.
- asHex(): The HMAC as string in hexadecimal format.
- asString(): The HMAC as string format.

Example:

lua

local data = crypto.utils.stream.fromString("ao")
local key = crypto.utils.array.fromString("super_secret_key")

crypto.mac.createHmac(data, key).asHex() -- 3966f45acb53f7a1a493bae15afecb1a204fa32d
crypto.mac.createHmac(data, key, "sha256").asHex() -- 542da02a324155d688c7689669ff94c6a5f906892aa8eccd7284f210ac66e2a7

KDFs

PBKDF2

The Password-Based Key Derivation Function 2 (PBKDF2) applies a pseudorandom function, such as hash-based message authentication code (HMAC), to the input password or passphrase along with a salt value and repeats the process many times to produce a derived key, which can then be used as a cryptographic key in subsequent operations.

Parameters:
- password (Array): The password to derive the key from.
- salt (Array): The salt to use.
- iterations (number): The number of iterations to perform.
- keyLen (number): The length of the key to derive.
- digest (string) optional: The digest algorithm to use. default is "sha1". Available algorithms are "sha1", "sha256".
Returns: A table containing functions to get derived key in different formats.
- asBytes(): The derived key as byte table.
- asHex(): The derived key as string in hexadecimal format.
- asString(): The derived key as string format.

Example:

lua

local salt = crypto.utils.array.fromString("salt")
local password = crypto.utils.array.fromString("password")
local iterations = 4
local keyLen = 16

local res = crypto.kdf.pbkdf2(password, salt, iterations, keyLen).asHex() -- C4C21BF2BBF61541408EC2A49C89B9C6

Utilities

Array

Example Usage:

lua


local arr = crypto.utils.array

arr.fromString("ao") -- Array
arr.toString(arr.fromString("ao")) -- ao

arr.fromHex("616f") -- Array
arr.toHex(arr.fromHex("616f")) -- 616f

arr.concat(arr.fromString("a"), arr.fromString("o")) -- Array
arr.truncate(arr.fromString("ao"), 1) -- Array

arr.XOR(arr.fromString("a"), arr.fromString("o")) -- Array

arr.substitute(arr.fromString("a"), arr.fromString("o")) -- Array
arr.permute(arr.fromString("a"), arr.fromString("o")) -- Array

arr.copy(arr.fromString("ao")) -- Array
arr.slice(arr.fromString("ao"), 0, 1) -- Array

`size`

Returns the size of the array.

Parameters:
- arr (Array): The array to get the size of.
Returns: The size of the array.

`fromString`

Creates an array from a string.

Parameters:
- str (string): The string to create the array from.
Returns: The array created from the string.

`toString`

Converts an array to a string.

Parameters:
- arr (Array): The array to convert to a string.
Returns: The array as a string.

`fromStream`

Creates an array from a stream.

Parameters:
- stream (Stream): The stream to create the array from.
Returns: The array created from the stream.

`readFromQueue`

Reads data from a queue and stores it in the array.

Parameters:
- queue (Queue): The queue to read data from.
- size (number): The size of the data to read.
Returns: The array containing the data read from the queue.

`writeToQueue`

Writes data from the array to a queue.

Parameters:
- queue (Queue): The queue to write data to.
- array (Array): The array to write data from.
Returns: None

`toStream`

Converts an array to a stream.

Parameters:
- arr (Array): The array to convert to a stream.
Returns: (Stream) The array as a stream.

`fromHex`

Creates an array from a hexadecimal string.

Parameters:
- hex (string): The hexadecimal string to create the array from.
Returns: The array created from the hexadecimal string.

`toHex`

Converts an array to a hexadecimal string.

Parameters:
- arr (Array): The array to convert to a hexadecimal string.
Returns: The array as a hexadecimal string.

`concat`

Concatenates two arrays.

Parameters:
- a (Array): The array to concatenate with.
- b (Array): The array to concatenate.
Returns: The concatenated array.

`truncate`

Truncates an array to a given length.

Parameters:
- a (Array): The array to truncate.
- newSize (number): The new size of the array.
Returns: The truncated array.

`XOR`

Performs a bitwise XOR operation on two arrays.

Parameters:
- a (Array): The first array.
- b (Array): The second array.
Returns: The result of the XOR operation.

`substitute`

Creates a new array with keys of first array and values of second

Parameters:
- input (Array): The array to substitute.
- sbox (Array): The array to substitute with.
Returns: The substituted array.

`permute`

Creates a new array with keys of second array and values of first array.

Parameters:
- input (Array): The array to permute.
- pbox (Array): The array to permute with.
Returns: The permuted array.

`copy`

Creates a copy of an array.

Parameters:
- input (Array): The array to copy.
Returns: The copied array.

`slice`

Creates a slice of an array.

Parameters:
- input (Array): The array to slice.
- start (number): The start index of the slice.
- stop (number): The end index of the slice.
Returns: The sliced array.

Stream

Stream is a data structure that represents a sequence of bytes. It is used to store and manipulate data in a streaming fashion.

Example Usage:

lua

local stream = crypto.utils.stream

local str = "ao"
local arr = {97, 111}

stream.fromString(str) -- Stream
stream.toString(stream.fromString(str)) -- ao

stream.fromArray(arr) -- Stream
stream.toArray(stream.fromArray(arr)) -- {97, 111}

stream.fromHex("616f") -- Stream
stream.toHex(stream.fromHex("616f")) -- 616f

`fromString`

Creates a stream from a string.

Parameters:
- str (string): The string to create the stream from.
Returns: The stream created from the string.

`toString`

Converts a stream to a string.

Parameters:
- stream (Stream): The stream to convert to a string.
Returns: The stream as a string.

`fromArray`

Creates a stream from an array.

Parameters:
- arr (Array): The array to create the stream from.
Returns: The stream created from the array.

`toArray`

Converts a stream to an array.

Parameters:
- stream (Stream): The stream to convert to an array.
Returns: The stream as an array.

`fromHex`

Creates a stream from a hexadecimal string.

Parameters:
- hex (string): The hexadecimal string to create the stream from.
Returns: The stream created from the hexadecimal string.

`toHex`

Converts a stream to a hexadecimal string.

Parameters:
- stream (Stream): The stream to convert to a hexadecimal string.
Returns: The stream as a hexadecimal string.

Hex

Example Usage:

lua

local hex = crypto.utils.hex

hex.hexToString("616f") -- ao
hex.stringToHex("ao") -- 616f

`hexToString`

Converts a hexadecimal string to a string.

Parameters:
- hex (string): The hexadecimal string to convert to a string.
Returns: The hexadecimal string as a string.

`stringToHex`

Converts a string to a hexadecimal string.

Parameters:
- str (string): The string to convert to a hexadecimal string.
Returns: The string as a hexadecimal string.

Queue

Queue is a data structure that represents a sequence of elements. It is used to store and manipulate data in a first-in, first-out (FIFO) fashion.

Example Usage:

lua

local q = crypto.utils.queue()

q.push(1)
q.push(2)
q.pop() -- 1
q.size() -- 1
q.getHead() -- 2
q.getTail() -- 2
q.reset()

`push`

Pushes an element to the queue.

Parameters:
- queue (Queue): The queue to push the element to.
- element (any): The element to push to the queue.
Returns: None

`pop`

Pops an element from the queue.

Parameters:
- queue (Queue): The queue to pop the element from.
- element (any): The element to pop from the queue.
Returns: The popped element.

`size`

Returns the size of the queue.

Parameters: None
Returns: The size of the queue.

`getHead`

Returns the head of the queue.

Parameters: None
Returns: The head of the queue.

`getTail`

Returns the tail of the queue.

Parameters: None
Returns: The tail of the queue.

`reset`

Resets the queue.

Parameters: None

Blueprints

Modules

0rbit (HTTP)

crypto ​

Overview ​

Usage ​

Primitives ​

Digests ​

MD2 ​

MD4 ​

MD5 ​

SHA1 ​

SHA2_256 ​

SHA2_512 ​

SHA3 ​

Blake2b ​

Ciphers ​

AES ​

Encrypt ​

Decrypt ​

ISSAC Cipher ​

Encrypt ​

Decrypt ​

random ​

Morus Cipher ​

Encrypt ​

Decrypt ​

NORX Cipher ​

Encrypt ​

Decrypt ​

Random Number Generators ​

MACs ​

HMAC ​

KDFs ​

PBKDF2 ​

Utilities ​

Array ​

size ​

fromString ​

toString ​

fromStream ​

readFromQueue ​

writeToQueue ​

toStream ​

fromHex ​

toHex ​

concat ​

truncate ​

XOR ​

substitute ​

permute ​

copy ​

slice ​

Stream ​

fromString ​

toString ​

fromArray ​

toArray ​

fromHex ​

toHex ​

Hex ​

hexToString ​

stringToHex ​

Queue ​

push ​

pop ​

size ​

getHead ​

getTail ​

reset ​

crypto

Overview

Usage

Primitives

Digests

MD2

MD4

MD5

SHA1

SHA2_256

SHA2_512

SHA3

Blake2b

Ciphers

AES

Encrypt

Decrypt

ISSAC Cipher

Encrypt

Decrypt

random

Morus Cipher

Encrypt

Decrypt

NORX Cipher

Encrypt

Decrypt

Random Number Generators

MACs

HMAC

KDFs

PBKDF2

Utilities

Array

`size`

`fromString`

`toString`

`fromStream`

`readFromQueue`

`writeToQueue`

`toStream`

`fromHex`

`toHex`

`concat`

`truncate`

`XOR`

`substitute`

`permute`

`copy`

`slice`

Stream

`fromString`

`toString`

`fromArray`

`toArray`

`fromHex`

`toHex`

Hex

`hexToString`

`stringToHex`

Queue

`push`

`pop`

`size`

`getHead`

`getTail`

`reset`